Application programming interface for implementing directory service access using directory service markup language

ABSTRACT

A set of DSML application programming interface (DSML API) functions is provided to facilitate the implementation of DSML-based directory service access. The DSML API includes a DSML document API class for building or accessing a DSML payload, and a DSML connection API class that handles connection and transport to a DSML server. To access a directory service, the client calls functions of the DSML document API class to generate a DSML request payload, and calls functions of the DSML connection API to transport a packet with the DSML request payload according to a pre-selected connection protocol, such as SOAP, to the DSML server for forwarding to the directory service.

TECHNICAL FIELD

[0001] This invention relates generally to computer software, and moreparticularly to software programming for implementing Directory ServiceMarkup Language (DSML)-based directory service access.

BACKGROUND OF THE INVENTION

[0002] Directory Service Markup Language is an OASIS (Organization forthe Advancement of Structured Information Standards) approved standardspecification that defines directory operations (e.g., LightweightDirectory Access Protocol (LDAP)) in XML form. The DSML v.2specification has been widely adopted by many software and hardwarevendors in the field of directory services.

[0003] In one popular approach to implementing directory service accessusing the DSML v.2 (e.g., the DSML Services for Windows (DSFW) ofMicrosoft Corporation), a DSML server is provided as an intermediatebetween a client and a directory service (e.g., the Active Directory ofMicrosoft Corporation). To use the directory service, the client sends aSimple Object Access Protocol (SOAP) packet with a DSML request as itspayload over the network connection to the DSML server. The DSML serverconverts the received DSML request into a LDAP request, and sends theLDAP request to the directory service. After the directory serviceresponds to the LDAP request, the DSML server converts the LDAP responseinto a DSML response payload, and return it to the requesting client ina SOAP response.

[0004] Although this scheme of enabling DSML-based access to thedirectory service is very successful, it requires the client to have theability to construct DSML payloads and handle SOAP packets. To developsuch client applications, the client application developers need to haveintimate knowledge of DSML v.2 and SOAP, which is often a difficultcondition to meet. According, there is a need to simplify the task ofclient application development to make it easier to utilize theDSML-based directory service access scheme as described above.

SUMMARY OF THE INVENTION

[0005] In view of the foregoing, the present invention provides a set ofDSML application programming interface (DSML API) functions that may becalled by a client application for handling DSML-based directory servicerequests and responses. In accordance with the invention, the DSML APIincludes a DSML document API class that concerns only building oraccessing a DSML payload and is independent of network connection, and aDSML connection API class that handles connection and transport to aDSML server that is independent of DSML document processing. To access adirectory service, the client calls API functions of the DSML documentAPI class to generate a DSML request payload, and calls API functions ofthe DSML connection API class to construct a request packet with theDSML request payload and transporting the request packet according to apre-selected connection protocol to the DSML server for forwarding tothe directory service.

BRIEF DESCRIPTION OF THE DRAWINGS

[0006]FIG. 1 is a block diagram generally illustrating an exemplarycomputer system on which an embodiment of the DSML API of the presentinvention may be implemented;

[0007]FIG. 2 is a schematic diagram showing an exemplary computernetwork having a client utilizing an embodiment of DSML API inaccordance with the invention for DSML-based directory service access;

[0008]FIG. 3 is a schematic diagram showing a class hierarchy of anembodiment of DSML API in accordance with the invention; and

[0009]FIG. 4 is a schematic diagram showing class elements of the DSMLAPI for building and manipulating a DSML payload.

DETAILED DESCRIPTION OF THE INVENTION

[0010] Turning to the drawings, wherein like reference numerals refer tolike elements, the invention is illustrated as being implemented in asuitable computing environment. Although not required, the inventionwill be described in the general context of computer-executableinstructions, such as program modules, being executed by a personalcomputer. Generally, program modules include routines, programs,objects, components, data structures, etc. that perform particular tasksor implement particular abstract data types. Moreover, those skilled inthe art will appreciate that the invention may be practiced with othercomputer system configurations, including hand-held devices,multi-processor systems, microprocessor-based or programmable consumerelectronics, network PCs, minicomputers, mainframe computers, and thelike. The invention may be practiced in distributed computingenvironments where tasks are performed by remote processing devices thatare linked through a communications network. In a distributed computingenvironment, program modules may be located in both local and remotememory storage devices.

[0011] The following description begins with a description of ageneral-purpose computing device that may be used in an exemplary systemfor implementing the invention, and the DSML API of the invention willbe described in greater detail with reference to FIGS. 2-4. Turning nowto FIG. 1, a general purpose computing device is shown in the form of aconventional personal computer 20, including a processing unit 21, asystem memory 22, and a system bus 23 that couples various systemcomponents including the system memory to the processing unit 21. Thesystem bus 23 may be any of several types of bus structures including amemory bus or memory controller, a peripheral bus, and a local bus usingany of a variety of bus architectures. The system memory includes readonly memory (ROM) 24 and random access memory (RAM) 25. A basicinput/output system (BIOS) 26, containing the basic routines that helpto transfer information between elements within the personal computer20, such as during start-up, is stored in ROM 24. The personal computer20 further includes a hard disk drive 27 for reading from and writing toa hard disk 60, a magnetic disk drive 28 for reading from or writing toa removable magnetic disk 29, and an optical disk drive 30 for readingfrom or writing to a removable optical disk 31 such as a CD ROM or otheroptical media.

[0012] The hard disk drive 27, magnetic disk drive 28, and optical diskdrive 30 are connected to the system bus 23 by a hard disk driveinterface 32, a magnetic disk drive interface 33, and an optical diskdrive interface 34, respectively. The drives and their associatedcomputer-readable media provide nonvolatile storage of computer readableinstructions, data structures, program modules and other data for thepersonal computer 20. Although the exemplary environment describedherein employs a hard disk 60, a removable magnetic disk 29, and aremovable optical disk 31, it will be appreciated by those skilled inthe art that other types of computer readable media which can store datathat is accessible by a computer, such as magnetic cassettes, flashmemory cards, digital video disks, Bernoulli cartridges, random accessmemories, read only memories, storage area networks, and the like mayalso be used in the exemplary operating environment.

[0013] A number of program modules may be stored on the hard disk 60,magnetic disk 29, optical disk 31, ROM 24 or RAM 25, including anoperating system 35, one or more applications programs 36, other programmodules 37, and program data 38. A user may enter commands andinformation into the personal computer 20 through input devices such asa keyboard 40 and a pointing device 42. Other input devices (not shown)may include a microphone, joystick, game pad, satellite dish, scanner,or the like. These and other input devices are often connected to theprocessing unit 21 through a serial port interface 46 that is coupled tothe system bus, but may be connected by other interfaces, such as aparallel port, game port or a universal serial bus (USB) or a networkinterface card. A monitor 47 or other type of display device is alsoconnected to the system bus 23 via an interface, such as a video adapter48. In addition to the monitor, personal computers typically includeother peripheral output devices, not shown, such as speakers andprinters.

[0014] The personal computer 20 may operate in a networked environmentusing logical connections to one or more remote computers, such as aremote computer 49. The remote computer 49 may be another personalcomputer, a server, a router, a network PC, a peer device or othercommon network node, and typically includes many or all of the elementsdescribed above relative to the personal computer 20, although only amemory storage device 50 has been illustrated in FIG. 1. The logicalconnections depicted in FIG. 1 include a local area network (LAN) 51 anda wide area network (WAN) 52. Such networking environments arecommonplace in offices, enterprise-wide computer networks, intranets andthe Internet.

[0015] When used in a LAN networking environment, the personal computer20 is connected to the local network 51 through a network interface oradapter 53. When used in a WAN networking environment, the personalcomputer 20 typically includes a modem 54 or other means forestablishing communications over the WAN 52. The modem 54, which may beinternal or external, is connected to the system bus 23 via the serialport interface 46. In a networked environment, program modules depictedrelative to the personal computer 20, or portions thereof, may be storedin the remote memory storage device. It will be appreciated that thenetwork connections shown are exemplary and other means of establishinga communications link between the computers may be used.

[0016] In the description that follows, the invention will be describedwith reference to acts and symbolic representations of operations thatare performed by one or more computers, unless indicated otherwise. Assuch, it will be understood that such acts and operations, which are attimes referred to as being computer-executed, include the manipulationby the processing unit of the computer of electrical signalsrepresenting data in a structured form. This manipulation transforms thedata or maintains it at locations in the memory system of the computer,which reconfigures or otherwise alters the operation of the computer ina manner well understood by those skilled in the art. The datastructures where data is maintained are physical locations of the memorythat have particular properties defined by the format of the data.However, while the invention is being described in the foregoingcontext, it is not meant to be limiting as those of skill in the artwill appreciate that various of the acts and operations describedhereinafter may also be implemented in hardware.

[0017] Referring to FIG. 2, the present invention is directed to a setof application programming interface (API) functions for a clientcomputer 70 on a network 68 (e.g., the Internet) to build and transportdirectory service requests in the Directory Service Markup Language(DSML) format and to process directory service responses. Specifically,in a preferred embodiment as shown in FIG. 2, the client 70 is connectedto a DSML server 80, which is in turn connected to a directory service90. In this context, the DSML server 80 may be considered as a “gateway”for network clients to access the directory service 90 using DSMLrequests. An application program 72 on the client machine may want toaccess the directory service 90. For example, the application programmay want to find the phone number of “John Smith” in a corporatedirectory via the Internet. As another example, the client device may bea small device such as a cellphone, and a user may use it to access theDSML server. To access the directory service 90, the client 70 forms aDSML request 76, and constructs a packet 78 according to a pre-selectedtransport protocol with the DSML request as its payload, and transportsthe request packet to the DSML server 80 under the selectedtransport/connection protocol. The transport/connection protocol may be,for example, the Simple Object Access Protocol (SOAP).

[0018] When the DSML server 80 receives the SOAP packet 78 that containsthe DSML request 76, it converts the DSML request to a request accordingto the Lightweight Directory Access Protocol (LDAP), which isimplemented by the directory service 90. The DSML server 80 thenforwards the LDAP request 82 to the directory service 90. In response,the directory service 90 returns a response 92 in the LDAP format to theDSML server 80. When the DSML server 80 receives the LDAP response 92,it converts the response to a response n the DSML format, puts the DSMLresponse 96 as the payload of a SOAP packet 98, and forwards the SOAPpacket with the DSML response to the requesting client.

[0019] In accordance with a feature of the invention, the operatingsystem of the client machine implements a set of application programminginterface (API) functions that the application program 72 may call tobuild DSML requests and process DSML responses, and to handle thetransport of the DSML requests and receipt of the DSML responses underthe pre-selected protocol, such as SOAP over HTTP, SMTP, DIME, etc. Thisset of API functions is hereinafter referred to as the DSML API 100. TheDSML API frees developers of client application programs from the taskof programming functions for handling the DSML and transport operations,thereby facilitating the use of the DSML-based directory service accessas described above by client applications.

[0020] By way of example, several scenarios are provided below toillustrate how the DSML API 100 may be used to enable DSML-baseddirectory service access. It will be appreciated, of course, that theuse of the DSML API is not limited to these scenarios. In a firstscenario, a smart cell phone or PDA device needs to access directoryinformation but does not contain an LDAP client. By including the DSMLAPI on the device, application programs can be written to employ the APIfunctions to form and send DSML requests for accessing the directoryservice through the DSML server. In a second scenario, a program on apersonal computer needs to access a directory service through afirewall, but the firewall is not allowed to pass LDAP protocol trafficbecause it is not capable of auditing such traffic. By using the DSMLAPI, applications on the personal computer can send SOAP packets with aDSML request payload, which can then pass through the firewall. In athird scenario, a programmer is writing an application using XMLprogramming tools and techniques, and the application needs to access adirectory. The DSML API is designed to allow a seamless integration withother XML programming. For instance, in DSML API object mode, theprogrammer is able to convert the DSML request to an XML documenteasily, allowing the programmer to manipulate it further using XMLprogramming or tools.

[0021] Referring now to FIG. 3, in accordance with a feature of anembodiment of the invention, the DSML API separates the aspect ofbuilding/processing DSML documents from the aspect of dealing with thetransport of the DSML documents, and makes them independent from eachother. Specifically, the DSML API 100 has a set of classes thatimplements the DSML payload/message, and another set of classes forhandling the transport. The transport may be, for example, SOAP overHTTP or DIME (“Direct Internet Message Encapsulation”), File, SMTP(“Simple Mail Transfer Protocol”), etc. The option “File” here meansthat the application reads or writes the DSML payload from or to a file,such as in the case of import and export. The separation of the DSMLdocument processing from the transport operations allows futuretransport protocols to be implemented without the need for anymodification of the classes for handling the DSML payload.

[0022] As illustrated in FIG. 3, the DSML API 100 has several top-levelclasses. As mentioned above, the DSML Connection class 110 deals withforming connections to the DSML server and handles remote and focaltransport protocols. In other words, the DSML Connection class providesa way to transport DSML documents. The DSML Document class 112, on theother hand, concerns only accessing or building a DSML payload, and isindependent of the connection aspect.

[0023] There are two classes, DSML Request Document and DSML ResponseDocument, that inherent from the top-level DSML Document class. The DSMLRequest Document class 122 defines functions for building a DSML requestpayload, such as AddRequest, ModifyRequest, SearchRequest, etc. On theother hand, the DSML Request Document class 126 contains thecorresponding response elements, such as AddResponse, ModifyResponse,SearchResponse, etc.

[0024] Referring now to FIG. 4, each item in the DSML Document class iscalled the “DSML Element.” Corresponding to the DSML requests andresponses, there are two types of DSML Elements: DSML Request Element132 and DSML Response Element 136. Both DSML Request Element and DSMLResponse Element further define more specialized classes. The DSMLElements for DSML documents are illustrated in FIG. 4 and will bedescribed in greater below. Having the specialized classes allows a userto provide strongly typed classes for each operation, and to definespecific constructors, properties, and methods, etc. FIG. 4 also shows aDSML Attribute class 116, and a DSML Control class 118, which arenormally embedded into DSML Element derived classes.

[0025] Returning to FIG. 3, the DSML Connection class 110 is a baseclass for different DSML bindings. In one embodiment, the DSML APIsupports SOAP over HTTP, and has corresponding DsmlSoapConnection class140 and a DsmlSoapHttpConnection classes 144. In alternativeembodiments, the API may support other bindings, such as SOAP over DIME,File binding, etc., with corresponding classes 146, 148 in thehierarchy. When a new protocol is implemented, this arranges allows theconnection class to be extended without disturbing the existing DSML APIsystem.

[0026] By way of example, the class definitions in one implementationfor some of the classes in FIG. 3, and some examples of how they may beused, are provided below.

[0027] The DSML Connection class and its subclasses are described first.

[0028] DsmlConnection

[0029] Overview:

[0030] DsmlConnection is an abstract class, which cannot beinstantiated. Each DSML binding (e.g SOAP, File) is expected to derivefrom this class. This class is primarily deals with connection-orientedcharacteristics, such as credentials, resource location, etc.

[0031] Class Type: Abstract

[0032] Protocol: DSML

[0033] Public Constructors: No public constructor. This is an abstractclass.

[0034] Public Properties:

[0035] NetworkCredentials Credentials

[0036] [Write-only] Allows the user to specify alternate credentials; ifnone is specified, it should default to the DefaultCredentials constant.

[0037] [Ready] Identifies the server the object is connected to.

[0038] For example, it might representhttp://abc.com/platforms/adssoap.dll for communicating with DSML Servervia SOAP, file://c:\data\employees.xml for using DSML via File Binding.

[0039] X509CertificateCollection ClientCertificates

[0040] [Readonly] Allows the user to specify one or more clientcertificates to be sent for authentication purpose.

[0041] TimeSpan TimeOut

[0042] Specified a time span before the request times out. The defaulttimeout is specified by the final non-abstract class.

[0043] Public Methods

[0044] abstract DsmlResponseDocument SendRequest(DsmlRequestDocumentrequest) Overridden by derived classes to provide a means of sending asingle directory operation to the server and returning the server'sresponse as a DsmlResponseDocurnent object. Will throw an exception onfailure.

[0045] DsmlSoapConnection

[0046] Overview:

[0047] Since DSML/SOAP can be implemented over many different protocols,such as HTTP, DIME, SMTP, etc, this class provides a higher level entitythat deals only with DSML and SOAP related features.

[0048] Derived From: DsmlConnection

[0049] Class Type: Abstract

[0050] Public Constructors: No public constructors.

[0051] Public Properties:

[0052] string SessionId {  get{ } }

[0053] Active Session ID. null indicates there is no active session.Session is activated by calling BeginSession( ).

[0054] XmlNode SoapRequestHeader {  get{ }  set{ } }

[0055] This method allows the user to retrieve and set the SOAPHeader(s) that will be attached to outgoing requests. The API will notattempt to parse these headers. The user may attach a sessionID headerhere if he or she so chooses, but the API will not use that sessionID aspart of its native support for session IDs (BeginSession/EndSession).For example, if the user initiates a session via the BeginSession( )method, and subsequently manually ends the session by attaching aEndSession header via this property, the API will still believe thesession is active (since the EndSession( ) method was never called). Theuser should take care to avoid such inconsistencies.

[0056] XmlNode SoapBody {  get{ }  set{ } }

[0057] It allows the users to modify the SOAP Body. Sometimes, othermessages are included along with DSML Body in the SOAP Body.

[0058] Public Methods

[0059] void BeginSession( )

[0060] Microsoft Dsml Session Support. It tells the DSFW (DSML Servicesfor Windows) to start a sessions. DSML Session is used for statelessprotocol such as HTTP against session-oriented features, such as PageControl.

[0061] Exception

[0062] Exception Class: InvalidOperationException

[0063] Thrown if the caller tries to BeginSession while a session isalready open on that connection

[0064] Text: “A session is already active on this connection.”

[0065] Exception Class: DsmlInvalidDocumentException

[0066] Server's response to BeginSession is not well-formed XML

[0067] Text: “The DSML document could not be parsed”

[0068] Exception Class: DsmlMissingSessionIdException

[0069] Server's response to BeginSession is missing the sessionID

[0070] Text: “The server failed to return a sessionID.”

[0071] Exception class: WebException

[0072] Communications failure with the DSML server.

[0073] void EndSession( )

[0074] Ends the session by sending an EndSession SOAP request to theDSML Server and clearing the SessionId property. If BeginSession has notbeen initiated, it throws an exception. It is possible the DSML Servermay have already terminated the session on its own (for example, due toidleness on the connection), and will therefore respond to a EndSessionSOAP request with an error. In such an event, the EndSession method isstill expected to clear the SessionId property on the LdapConnectionobject, in addition to returning the error to the caller (as aWebException).

[0075] Exception class: WebException

[0076] Communications failure with the DSML server.

[0077] Exception Class: InvalidOperationException

[0078] Thrown if caller tries to EndSession when no session is active

[0079] Text: “No session is currently active on this connection.”

[0080] DsmlSoapHttpConnection

[0081] Overview:

[0082] DsmlSoapHttpConnection creates a connection to a DSML Gatewayspecified in the Uri. The user may specify alternate credentials,authentication type.

[0083] The necessary HTTP header “Content-Type: text/xml” will beautomatically included by this class when sending a request.

[0084] The default timeout is 30 seconds.

[0085] Derived From: DsmlSoapConnection

[0086] Class Type: Concrete

[0087] Constructors:

[0088] DsmlSoapHttpConnection(DsmlDirectoryIdentifier ident)

[0089] Create Dsml Soap over HTTP connection for the server identifiedby ident. This identifier should represent a URI that is a DSML URLssetup by the Administrator. For examplehttp://myserver01.example.com/DSML/adssoap.dll. The default credentialsand the Windows Integrated Authentication will be used to connect to theDSML Server.

[0090] DsmlSoapHttpConnection(DsmlDirectoryIdentifier ident,NetworkCredential cred)

[0091] Create Dsml Soap over HTTP connection for a given server andCredentials.

[0092] DsmlSoapHttpConnection(

[0093] DsmlDirectoryIdentifier ident, NetworkCredential cred, AuthTypesauthType)

[0094] Create Dsml Soap over HTTP connection for a given server,Credentials, and authentication type.

[0095] Public Properties:

[0096] String SoapActionHeader;

[0097] Soap Action Header that will be sent along with other HTTPHeaders. By default it sets to “#batchRequest”

[0098] AuthTypes AuthType;

[0099] Authentication Type.

[0100] The supported authentication types are: “Anonymous”, “NTLM”,“Basic”, “Digest” and “Negotiate”.

[0101] DirectoryIdentifier Directory

[0102] [Readonly] Returns a DsmlDirectoryIdentifier identifying theserver that this object is connected to.

[0103] Public Methods:

[0104] DsmlResponseDocument SendRequest(DsmlRequestDocument request)

[0105] Override to send a single DsmlRequestDocument as a DSMLbatchRequest. Will throw an exception on failure.

[0106] Exception class: DsmlInvalidDocumentException

[0107] Client's request or Server's response was not well-formed DSMLdocument.

[0108] Text: Invalid [Request|Response] Dsml Document

[0109] Exception class: WebException

[0110] Communications failure with the DSML server.

[0111] Exception Class: S.DS.Common.OperationException

[0112] The operation returned a failure code (i.e., a code other thansuccess, compareTrue, compareFalse, or referral).

[0113] Text: “An error occurred in the operation.”

[0114] Exception Class: S.DS.Dsml.ErrorResponseException

[0115] The DSML server returned an <errorResponse>

[0116] Text: “An <errorResponse>was returned.”

[0117] DsmlResponseDocument SendRequest(DsmlRequestDocument request)

[0118] Sends the DsmlRequestDocument to the DSML Server. If it issuccessful, a DsmlResponseDocument will be returned. Otherwise anexception will be thrown.

[0119] Exception:

[0120] Exception class: DsmlInvalidDocumentException

[0121] Client's request or Server's response was not well-formed DSMLdocument.

[0122] Text: Invalid [Request|Response] Dsml Document

[0123] Exception class: WebException

[0124] Communications failure with the DSML server

[0125] DsmlResponseDocument SendRequest(Stream stream)

[0126] Sends a DSML request specified by stream. This method shoulddynamically stream the request to the DSML Server, i.e., it should nottry to load the entire contents of the stream into memory before sendingthe request to the server.

[0127] Exception class: DsmlInvalidDocumentException

[0128] Client's request or Server's response was not well-formed DSMLdocument.

[0129] Text: Invalid [Request|Response] Dsml Document

[0130] Exception class: WebException

[0131] Communications failure with the DSML server.

[0132] Several connection examples using the DSML API are providedbelow.

EXAMPLE 1 Connecting to a DSML Server and Sending a Document Request

[0133] DsmlSoapHttpConnection con = new DsmlSoapHttpConnection   (newDsmlDirectoryIdentifier(    “http://myserver.fabrikam.com/hr/adssoap.dll”)); DsmlRequestDocumentreq = new DsmlRequestDocument( ); // // Construct the Dsml Request here.... // DsmlResponseDocument resp = con.SendRequest(req); // // Readingthe response document here.... //

EXAMPLE 2 DSML Connection with SSL and Basic Authentication

[0134] DsmlSoapHttpConnection con=new DsmlSoapHttpConnection(

[0135] new DsmlDirectoryIdentifier(

[0136] “https://myserver.fabrikam.com/hr/adssoap.dll”),

[0137] new NetworkCredential(username,password),

[0138] AuthTypes.Basic);

EXAMPLE 3 DSML Connection with Session

[0139] DsmlSoapHttpConnection con=new DsmlSoapHttpConnection(

[0140] new DsmlDirectoryIdentifier(

[0141] “https://myserver.fabrikam.com/hr/adssoap.dll”),

[0142] new NetworkCredential(username,password),

[0143] AuthTypes.Basic);

[0144] DsmlRequestDocument doc1=. . . .

[0145] DsmlRequestDocument doc2=. . . .

[0146] con.BeginSession( );

[0147] con.SendRequest(doc1);

[0148] con.SendRequest(doc2);

[0149] con.EndSession( );

EXAMPLE 4 DSML Using Client-Certificate Authentication

[0150] DsmlSoapConnection con=new DsmlSoapHttpConnection(

[0151] new DsmlDirectoryIdentifier(

[0152] “https://myserver.fabrikam.com/hr/adssoap.dll”),

[0153] null,

[0154] AuthTypes.Basic);

[0155] DsmlRequestDocument doc=. . . .

[0156]con.ClientCertificates.Add(X509Certificate.CreateFromCertFile@“c:\user.cer”));

[0157] con. SendRequest(doc);

[0158] The DSML Document class and its subclasses are described next.

[0159] DsmlDocument

[0160] Overview:

[0161] DsmlDocument is an abstract class to construct, manipulate a DsmlDocument. It's a base class for both DsmlRequestDocument andDsmlResponseDocument. DsmlDocument supports collections and index. Eachitem in its collection is an object that is derived from DsmlElement.The objective of DsmlDocument is to provide a container that holdsmultiple DsmlElements for batched protocols, namely, DSML. It also holdsthe responses for a batched operation. Note that DsmlDocument and itsderived classes are particular to the DSML protocol.

[0162] Derived From: Object

[0163] Class Type: Abstract

[0164] Constructors: No public constructor. This is an abstract class.

[0165] Public Properties:

[0166] Virtual String RequestID;

[0167] RequestID associated with the document.

[0168] Public Methods:

[0169] XmlDocument ToXml( )

[0170] Return XmlDocument object that contains DsmlDocument in DSML v2format.

[0171] Exceptions:

[0172] Exception Class: DirectoryAttributeNullException

[0173] Thrown if, while encoding the XML to send a request, DSML APIencounters a null reference in the Values array of a DirectoryAttributeor DirectoryAttributeModification. Note that when they set theattributes on a AddRequest, etc., object, DSML API does check the Valuesarray at that time and throw an ArgumentException if a null reference isfound. However, since they can change theDirectoryAttribute/DirectoryAttributeModification object outside of DSMLAPI (ref. vs. copy semantics), DSML API also has to account for thiswhen it comes time to actually use the Values array.

[0174] Text: “A null reference was detected in the Values array of aDirectoryAttribute or DirectoryAttributeModification object.”

[0175] DsmlRequestDocument

[0176] Overview:

[0177] DsmlRequestDocument contains zero or moreDsmlRequestDocument-derived objects. The user may add, delete, modify,enumerate the DsmlRequestDocument before sending to the server.

[0178] DsmlRequestDocument can be used with any DSML Binding classes totransport the document; for example DsmlSoapHttpConnection.DsmlRequestDocument corresponds to the BatchRequest type defined in theDSMlv2 XSD.

[0179] Derived From: DsmlDocument

[0180] Implements: IList, IEnumerable

[0181] Class Type: Concrete

[0182] Constructors:

[0183] DsmlRequestDocument( )

[0184] Creating an empty request document.

[0185] Public Properties:

[0186] Collection/Index Related Properties bool IList:IsFixedSize.

[0187] Request document will not be a fixed size; while Responsedocument will be a fixed size.

[0188] bool ILIst:IsReadOnly.

[0189] Request document will be read and write; while Response documentwill be readonly.

[0190] object ICollection.SyncRoot.

[0191] Gets an object that can be used to synchronize access to thecollection object

[0192] bool ICollection.IsSynchronized.

[0193] Indicates whether access to this collection object issynchronized

[0194] public int Count.

[0195] Gets the number of objects in side this collection object

[0196] int ICollection.Count.

[0197] Gets the number of objects in side this collection object

[0198] public DsmlRequestDocument this[int index].

[0199] Gets or sets the element at the specified index

[0200] object IList.this[int index]

[0201] Gets or sets the element at the specified index

[0202] DsmlDocumentProcessing DocumentProcessing

[0203] Optional Either DsmlDocumentProcessing.Sequential orDsmlProcessing.Parallel. The default isDsmlDocumentProcessing.Sequential.

[0204] DsmlResponseOrder ResponseOrder

[0205] Optional. It could be either DsmlResponseOrder.Sequential or

[0206] DsmlResponseOrder.Unordered. The default isDsmlResponseOrder.Sequential

[0207] DsmlErrorProcessing ErrorProcessing

[0208] Optional. It could be either DsmlErrorProcessing.Resume orDsmlResponseOrder.Exit. The default is DsmlErrorProcessing.Exit

[0209] Public Methods:

[0210] Collection/Index Related Methods

[0211] public lEnumerator GetEnumerator( )

[0212] Returns an enumerator that can enumerate this collection

[0213] public int Add(DsmlRequestDocument request)

[0214] Add an element to this collection object

[0215] int IList.Add(object request)

[0216] Add an element to this collection object

[0217] void Clear( )

[0218] Removes all items from this collection object

[0219] void IList.Clear( )

[0220] Removes all items from this collection object

[0221] public bool Contains(DsmlRequestDocument value)

[0222] Determins whether this collection object contains a specificvalue

[0223] bool IList.Contains(Object value)

[0224] Determins whether this collection object contains a specificvalue

[0225] public int IndexOf(DsmlRequestDocument value)

[0226] Determines the index of a specific item in the collection object

[0227] int IList.IndexOf(object value)

[0228] Determines the index of a specific item in the collection object

[0229] public void Insert(int index,DsmlRequestDocument value)

[0230] Insert the item to the collection object at the specifiedposition

[0231] void IList.Insert(int index,object value)

[0232] Insert the item to the collection object at the specifiedposition

[0233] public void Remove(DsmlRequestDocument value)

[0234] Removes the first occurrence of a specific DsmlRequestDocumentobject in the collection

[0235] void IList.Remove(object value)

[0236] Removes the first occurrence of a specific DsmlRequestDocumentobject in the collection

[0237] void RemoveAt(int index)

[0238] Removes the item at the specified position

[0239] void IList.RemoveAt(int index)

[0240] Removes the item at the specified position

[0241] public void CopyTo(DsmlRequestDocument[ ] value, int i)

[0242] Copies the elements of the collection object to aDsmlRequestDocument array

[0243] void ICollection.CopyTo(Array value, int i)

[0244] Copies the elements of the collection object to an array

[0245] DsmlResponseDocument

[0246] Overview:

[0247] DsmlResponseDocument is generated by sending theDsmlRequestDocument.

[0248] DsmlResponseDocument is readonly collection that contains zero ormore DsmlResponseDocument-derived objects.

[0249] Derived From: DsmlDocument

[0250] Class Type: Concrete

[0251] Constructors: None. DsmlResponseDocument cannot be created by theuser.

[0252] Public Properties:

[0253] bool IsErrorResponse

[0254] [Read-only] Return whether an error response has occurred.

[0255] bool IsOperationError

[0256] [Read-only] Return whether an operation error response hasoccurred.

[0257] String RequestID {set { . . . }}

[0258] The inherited (from DsmlDocument) RequestID property isoverloaded to throw an exception on set, making it effectivelyread-only.

[0259] Exception Class: NotSupportedException

[0260] Text: “The property is read-only”.

[0261] Collection/Index Related Properties.

[0262] object ICollection.SyncRoot.

[0263] Gets an object that can be used to synchronize access to thecollection object

[0264] bool ICollection.IsSynchronized.

[0265] Indicates whether access to this collection object issynchronized

[0266] public int Count.

[0267] Gets the number of objects in side this collection object

[0268] int ICollection.Count.

[0269] Gets the number of objects in side this collection object

[0270] public DsmlResponseDocument this[int index]

[0271] Readonly. Gets the element at the specified index

[0272] Public Methods:

[0273] Collection/Index Related Methods.

[0274] public lEnumerator GetEnumerator( )

[0275] Returns an enumerator that can enumerate this collection

[0276] public void CopyTo(DsmlResponseDocument[ ] value, int i)

[0277] Copies the elements of the collection object to aDsmlResponseDocument array

[0278] void ICollection.CopyTo(Array value, int i)

[0279] Copies the elements of the collection object to an array

[0280] DsmlResponseDocument this

[0281]

[0282] [Read-only] Returns the DsmlResponseDocument with the specifiedrequestID.

[0283] Exception class: InvalidOperationException

[0284] Thrown if the collection contains more than oneDsmlResponseDocument with the specified requestID.

[0285] Text: “Multiple responses match the specified requestID.”

[0286] The following are examples of how the DSML Document classes maybe called.

[0287] DsmlRequestDocument doc=new DsmlRequestDocument( );

[0288] doc.ErrorProcessing=DsmlErrorProcessing.Resume;

[0289] //adding the request element to the document

[0290] doc.Add(new AddRequest( . . . ));

[0291] doc.Add(new SearchRequest( . . . ));

[0292] //demonstrate retrieving element via position;

[0293] DsmlRequestElement element=doc[1]; //retrieve the second requestelement.

[0294] DsmlSoapHttpConnection con=new DsmlSoapHttpConnection(

[0295] new DsmlDirectoryIdentifier(“http://a.b.com/os/adssoap.dll”));

[0296] DsmlResponseDocument resp=con.SendRequest(doc);

[0297] //Getting the responses

[0298] AddResponse add=(AddResponse) resp[0];

[0299] SearchResponse src=(SearchResponse) resp[1]; // enumerating theresponse foreach( DsmlResponseElement r in resp ) { Console.WriteLine(r); }

[0300] In view of the many possible embodiments to which the principlesof this invention may be applied, it should be recognized that theembodiments described herein with respect to the drawing figures aremeant to be illustrative only and should not be taken as limiting thescope of the invention. Therefore, the invention as described hereincontemplates all such embodiments as may come within the scope of thefollowing claims and equivalents thereof.

What is claimed is:
 1. A computer-readable medium havingcomputer-executable instructions for performing steps for accessing adirectory service, comprising: calling a first API function defined in adocument API class to construct a DSML request; and calling a second APIfunction defined in a connection API class to send a request packethaving the DSML request as a payload under a networking protocol.
 2. Acomputer-readable medium as in claim 1, wherein the networking protocolincludes SOAP.
 3. A computer-readable medium as in claim 2, wherein therequest packet is sent using SOAP over HTTP.
 4. A computer-readablemedium as in claim 2, wherein the request packet is sent using SOAP overDIME.
 5. A computer-readable medium as in claim 1, wherein the requestpacket is sent over a FILE binding.
 6. A computer-readable medium as inclaim 1, wherein the request packet is sent to a DSML server forforwarding to the directory service.
 7. A computer-readable medium as inclaim 1, having further computer-executable instructions for performingsteps of: receiving a response packet having a DSML response as apayload; calling a third API function of the document API class toprocess the DSML response.
 8. A computer-readable medium as in claim 1,wherein the document API class and the connection API class are separateand independent from each other.
 9. A method of accessing a directoryservice, comprising: calling a first API function defined in a documentAPI class to construct a DSML request; calling a second API functiondefined in a connection API class to send a request packet having theDSML request as a payload under a networking protocol.
 10. A method asin claim 9, wherein the networking protocol includes SOAP.
 11. A methodas in claim 10, wherein the request packet is sent using SOAP over HTTP.12. A method as in claim 10, wherein the request packet is sent usingSOAP over DIME.
 13. A method as in claim 9, wherein the request packetis sent over a FILE binding.
 14. A method as in claim 9, wherein therequest packet is sent to a DSML server for forwarding to the directoryservice.
 15. A method as in claim 9, having further computer-executableinstructions for performing steps of: receiving a response packet havinga DSML response as a payload; calling a third API function of thedocument API class to process the DSML response.
 16. A method as inclaim 9, wherein the document API class and the connection API class areseparate and independent from each other.
 17. A computer-readable mediumhaving computer-executable instructions for performing API functions foraccessing a directory service using DSML, comprising: a first group ofAPI functions defined by a document API class for building a DSMLrequest and processing a DSML response; a second group of API functionsdefined by a connection API class, including functions for sending arequest packet having the DSML request as a payload under a transportprotocol, wherein the document API class and connection API class areseparate and independent from each other.
 18. A computer-readable mediumas in claim 17, wherein the networking protocol includes SOAP.
 19. Acomputer-readable medium as in claim 17, wherein the request packet issent using SOAP over HTTP.
 20. A computer-readable medium as in claim17, wherein the request packet is sent to a DSML server for forwardingto the directory service.